<!doctype html>
<html>
    <head>
        <title>HT 刻度尺手册</title>
        <meta charset="UTF-8">    
        <meta name="viewport" content="user-scalable=yes, width=1024">
        <style type="text/css"> 
            h1, h2, h3, h4, h5, h6, p, blockquote {
                margin: 0;
                padding: 0;
            }
            body {
                font-family: "Helvetica Neue", Helvetica, "Hiragino Sans GB", Arial, sans-serif;
                font-size: 13px;
                line-height: 18px;
                color: #737373;
                background-color: white; 
                margin: 10px 13px 10px 13px;
            }
            table {
                margin: 10px 0 15px 0;
                border-collapse: collapse;
            }
            td,th {	
                border: 1px solid #ddd;
                padding: 3px 10px;
            }
            th {
                padding: 5px 10px;	
            }
            a {
                color: #0069d6;
            }
            a:hover {
                color: #0050a3;
                text-decoration: none;
            }
            a img {
                border: none;
            }
            p {
                margin-bottom: 9px;
            }
            h1, h2, h3, h4, h5, h6 {
                color: #404040;
                line-height: 36px;
            }
            h1 {
                margin-bottom: 18px;
                font-size: 30px;
            }
            h2 {
                font-size: 24px;
            }
            h3 {
                font-size: 18px;
            }
            h4 {
                font-size: 16px;
            }
            h5 {
                font-size: 14px;
            }
            h6 {
                font-size: 13px;
            }
            hr {
                margin: 0 0 19px;
                border: 0;
                border-bottom: 1px solid #ccc;
            }
            blockquote {
                padding: 13px 13px 21px 15px;
                margin-bottom: 18px;
                font-family:georgia,serif;
                font-style: italic;
            }
            blockquote:before {
                content:"\201C";
                font-size:40px;
                margin-left:-10px;
                font-family:georgia,serif;
                color:#eee;
            }
            blockquote p {
                font-size: 14px;
                font-weight: 300;
                line-height: 18px;
                margin-bottom: 0;
                font-style: italic;
            }
            code, pre {
                font-family: Monaco, Andale Mono, Courier New, monospace;
            }
            code {
                background-color: #fee9cc;
                color: rgba(0, 0, 0, 0.75);
                padding: 1px 3px;
                font-size: 12px;
                border-radius: 3px;
            }
            pre {
                display: block;
                padding: 14px;
                margin: 0 0 18px;
                line-height: 16px;
                font-size: 11px;
                border: 1px solid #d9d9d9;
                white-space: pre-wrap;
                word-wrap: break-word;
            }
            pre code {
                background-color: #fff;
                color:#737373;
                font-size: 11px;
                padding: 0;
            }
            sup {
                font-size: 0.83em;
                vertical-align: super;
                line-height: 0;
            }
            * {
                -webkit-print-color-adjust: exact;
            }
            @media screen and (min-width: 914px) {
                body {
                    width: 854px;
                    margin:10px auto;
                }
            }
            @media print {
                body,code,pre code,h1,h2,h3,h4,h5,h6 {
                    color: black;
                }
                table, pre {
                    page-break-inside: avoid;
                }
            }                        
            iframe{
                width: 100%;
                border: 1px solid #34495E;
                margin: 0;                
            }            
            .logo{
                vertical-align: middle;
            }

        </style>        
        <script>
            function init() {
                var logoSrc = '',
                    logos = document.querySelectorAll('.logo'),
                    i = 0;
                for (; i < logos.length; i++) {
                    logos[i].src = logoSrc;
                }
                
                var iframes = document.querySelectorAll('iframe'),
                    func = function(){};
                for (i=0; i < iframes.length; i++) {
                    var iframe = iframes[i];
                    
                    // a small hack to make it work on android
                    iframe.ontouchstart = func;
                    
                    var div = document.createElement('div');
                    div.innerHTML = '<a href="' + iframe.src + '" target="_blank">独立运行→</a>';
                    iframe.parentNode.insertBefore(div, iframe);
                }   
            }
        </script>    
    </head>
    <body onload="init();">
        <a href="http://www.hightopo.com"><img class="logo"></a>HT 刻度尺手册
        <hr style="margin: 1px 0 20px 0">
<p>索引</p>

<ul><li><a href="#ref_description">概述</a></li><li><a href="#ref_graphview">示例一：为拓扑增加刻度尺</a></li><li><a href="#ref_widget">示例二：为通用组件增加刻度尺</a></li></ul>

<hr/>

<div id="ref_description"></div>

<h3>概述</h3>

<p><code>ht.widget.RulerFrame</code>用于为<code>HT</code>组件(拓扑和树、表格等通用组件)及<code>HTML</code>元素(如<code>div</code>)提供刻度尺，
<code>RulerFrame</code>可以在组件的上、右、下、左四条边上绘制刻度，刻度可根据用户的操作(缩放、滚动)自动调节。
在正式使用<code>API</code>之前，您的页面里应该引入相关<code>js</code>：</p>

<pre><code>&lt;script src=&quot;ht.js&quot;&gt;&lt;/script&gt; &lt;!--先引入ht.js--&gt;
&lt;script src=&quot;ht-rulerframe.js&quot;&gt;&lt;/script&gt;</code></pre>

<p><code>RulerFrame</code>提供的<code>API</code>如下：</p>

<ul><li><code>defaultRulerConfig</code>通过<code>getDefaultRulerConfig()</code>和<code>setDefaultRulerConfig(&#39;newConfig&#39;)</code>操作，总控所有刻度尺的属性</li><li><code>topRulerConfig</code>通过<code>getTopRulerConfig()</code>和<code>setTopRulerConfig(&#39;newConfig&#39;)</code>操作，用于控制上刻度尺的属性</li><li><code>rightRulerConfig</code>通过<code>getRightRulerConfig()</code>和<code>setRightRulerConfig(&#39;newConfig&#39;)</code>操作，用于控制右刻度尺的属性</li><li><code>bottomRulerConfig</code>通过<code>getBottomRulerConfig()</code>和<code>setBottomRulerConfig(&#39;newConfig&#39;)</code>操作，用于控制下刻度尺的属性</li><li><code>leftRulerConfig</code>通过<code>getLeftRulerConfig()</code>和<code>setLeftRulerConfig(&#39;newConfig&#39;)</code>操作，用于控制左刻度尺的属性</li><li><code>component</code>表示要增加刻度尺的组件，通过<code>getComponent()</code>和<code>setComponent(component)</code>操作，可以是<code>HT</code>组件，也可以是<code>HTML</code>元素</li><li><p><code>addComponentPropertyChangeListener(component, handler)</code>为<code>component</code>增加属性变化监听器，默认实现如下：</p><pre><code>if (component &amp;&amp; component.mp) component.mp(handler);</code></pre><p><code>HTML</code>元素没有提供<code>mp</code>接口，所以如果<code>component</code>为<code>HTML</code>元素，就需要重写此方法。另外需要注意，重写此方法后必须调用<code>setComponent()</code>，
以便<code>RulerFrame</code>能正确监听到<code>component</code>的属性变化。换句话说，如果<code>component</code>为<code>HTML</code>元素，不能在<code>RulerFrame</code>的构造函数中传入<code>component</code>，
而是应该先重写<code>addComponentPropertyChangeListener</code>再调用<code>setComponent()</code></p></li><li><code>removeComponentPropertyChangeListener(component, handler)</code>删除<code>component</code>上的属性变化监听器，如果重写了<code>addComponentPropertyChangeListener</code>，
也要重写此方法删除监听器，以免造成内存泄露</li><li><p><code>getComponentViewRect(component)</code>获得<code>component</code>的可视范围，默认实现如下：</p><pre><code>if (component &amp;&amp; component.getViewRect) return component.getViewRect();</code></pre><p><code>HTML</code>元素没有提供<code>getViewRect</code>接口，所以如果<code>component</code>为<code>HTML</code>元素，需要重写此方法</p></li><li><p><code>invalidateComponent(component)</code>使<code>component</code>无效。默认实现如下：</p><pre><code>if (component &amp;&amp; component.iv) component.iv();</code></pre><p><code>HTML</code>元素没有提供<code>iv</code>接口，直接忽略此方法即可。对于特殊的<code>HT</code>组件(如<code>TablePane</code>)，内部封装了多个组件(<code>TableHeader</code>和<code>TableView</code>)，
需要重写此方法，无效当前<code>component</code>及子<code>component</code></p></li><li><code>validateComponent</code>使<code>component</code>立即生效，同<code>invalidateComponent</code>一样，如果<code>component</code>内部封装了其它组件，需要重写此方法，使子<code>component</code>也生效</li><li><code>dispose()</code>销毁此组件</li></ul>

<p><code>setDefaultRulerConfig</code>的参数为一个<code>js</code>对象，此对象提供所有刻度尺的默认配置，支持的属性如下：</p>

<ul><li><code>size</code>指定刻度尺的宽度，默认为<code>20</code>,</li><li><code>borderWidth</code>指定刻度尺的边框宽度，默认为<code>1</code>,</li><li><code>borderStyle</code>指定刻度尺的边框样式，支持<code>css</code>提供的所有边框样式，默认为<code>solid</code></li><li><code>borderColor</code>指定刻度尺的边框颜色，默认为<code>#888</code></li><li><code>tickSpacingAdaptable</code>是否自动调整刻度尺主刻度之间的间距，默认为<code>true</code></li><li><code>minMajorTickSpacing</code> 主刻度之间的最小间距，默认为<code>10</code></li><li><code>defaultMajorTickSpacing</code>指定刻度尺主刻度之间的间距，默认为<code>50</code>,</li><li><code>minPhysicalMajorTickSpacing</code>指定刻度尺主刻度之间的最小屏幕像素，如果<code>tickSpacingAdaptable</code>为<code>true</code>并且主刻度之间的屏幕像素小于此属性指定的值，
则自动扩大主刻度之间的间距;默认值为<code>50</code></li><li><code>maxPhysicalMajorTickSpacing: </code>指定刻度尺主刻度之间的最大屏幕像素，如果<code>tickSpacingAdaptable</code>为<code>true</code>并且主刻度之间的屏幕像素大于此属性指定的值，
则自动收缩主刻度之间的间距;默认值为<code>100</code></li><li><code>majorTickTextFont</code>指定主刻度文字的字体，默认为<code>12px Arial</code></li><li><code>majorTickTextColor</code>指定主刻度文字的颜色，默认为<code>#666</code></li><li><code>majorTickColor</code>指定主刻度标记的颜色，默认为<code>#888</code></li><li><code>minorTickColor</code>指定小刻度标记的颜色，默认为<code>#ccc</code></li><li><code>background</code>指定刻度尺背景色，默认为<code>rgba(0,0,0,0)</code></li><li><code>guideVisible</code>参考线是否可见，默认为<code>false</code></li><li><code>guideColor</code>指定参考线颜色，默认为<code>rgb(0, 173, 239)</code></li><li><code>guideWidth</code>指定参考线宽度，默认为<code>2</code></li><li><code>guideTipVisible</code> 指定参考线提示框是否可见,默认为<code>false</code></li><li><code>guideTipBorderColor</code> 指定参考线提示框边框颜色，默认为<code>#666</code></li><li><code>guideTipTextColor</code> 指定参考线提示框内的文本颜色，默认为<code>#666</code></li><li><code>guideTipTextFont</code> 指定参考线提示框内的文本字体，默认为<code>12px Arial</code></li><li><code>guideTipBackground</code> 指定参考线提示框的背景颜色，默认为<code>#fff</code></li></ul>

<p>每个刻度尺可配置的属性同<code>defaultRulerConfig</code>一致，但优先级高于默认配置。另外,单个刻度尺可配置<code>visible</code>属性，用于控制当前刻度尺是否可见，
默认只显示左、上两个刻度尺。</p>

<p>如果只要修改某个属性，可通过下面代码实现：</p>

<pre><code>rulerFrame.getLeftRulerConfig().size = 30;
rulerFrame.iv();</code></pre>

<div id="ref_graphview"></div>

<h3>示例一：为拓扑增加刻度尺</h3>

<p><iframe src="examples/example_forgraphview.html" style="height:250px"></iframe></p>

<div id="ref_menushowwithapi"></div>

<pre><code>var dataModel = new ht.DataModel(),
    graphView = new ht.graph.GraphView(dataModel),
    rulerFrame = new ht.widget.RulerFrame(graphView),
    view = rulerFrame.getView();
rulerFrame.getDefaultRulerConfig().guideVisible = true;
rulerFrame.getDefaultRulerConfig().guideTipVisible = true;
rulerFrame.getDefaultRulerConfig().guideTipBackground = &quot;rgb(0, 173, 239)&quot;;
rulerFrame.getDefaultRulerConfig().guideTipTextColor = &quot;white&quot;;

rulerFrame.getLeftRulerConfig().background = &quot;yellow&quot;;
rulerFrame.getLeftRulerConfig().tickSpacingAdaptable = false;
rulerFrame.getLeftRulerConfig().defaultMajorTickSpacing = 100;
rulerFrame.getLeftRulerConfig().guideTipVisible = false;

rulerFrame.getTopRulerConfig().guideTipVisible = false;

rulerFrame.getRightRulerConfig().visible = true;

rulerFrame.getBottomRulerConfig().visible = true;

rulerFrame.iv();
//...
document.body.appendChild(view);</code></pre>

<p>缩小拓扑可以发现左刻度尺的刻度挤在一起，因为我们将其<code>tickSpacingAdaptable</code>设为了<code>false</code>，主刻度之间的间距不会自动调整。</p>

<div id="ref_widget"></div>

<h3>示例二：为通用组件增加刻度尺</h3>

<p><iframe src="examples/example_forwidget.html" style="height:350px"></iframe></p>

<div id="ref_menushowwithapi"></div>

<pre><code>rightRulerFrame.getLeftRulerConfig().visible = false;
rightRulerFrame.getRightRulerConfig().visible = true;
centerRulerFrame.getRightRulerConfig().visible = true;

leftRulerFrame.getView().style.position = &quot;absolute&quot;;
rightRulerFrame.getView().style.position = &quot;absolute&quot;;
centerRulerFrame.getView().style.position = &quot;absolute&quot;;

/* TablePane的滚动由内部的TableView实现，所以需要重写此方法增加监听器*/
leftRulerFrame.addComponentPropertyChangeListener = function(component, handler){
    component.getTableView().mp(handler);
};
leftRulerFrame.removeComponentPropertyChangeListener = function(component, handler){
    component.getTableView().ump(handler);
};
/* 返回内部TableView的ViewRect*/
leftRulerFrame.getComponentViewRect = function(component) {
    return component.getTableView().getViewRect();
};
/* 使TablePane和内部的TableView无效*/
leftRulerFrame.invalidateComponent = function(component) {
    component.iv();
    component.getTableView().iv();
};
/* 使TablePane和内部的TableView生效*/
leftRulerFrame.validateComponent =  function(component) {
    component.validate();
    component.getTableView().validate();
};

/* HTML元素没有mp方法，为其scroll事件增加监听器*/
centerRulerFrame.addComponentPropertyChangeListener = function(component, handler){
    component.addEventListener(&quot;scroll&quot;, handler);
};
centerRulerFrame.removeComponentPropertyChangeListener = function(component, handler){
    component.removeEventListener(&quot;scroll&quot;, handler);
};
/* 返回HTML元素的可视区域*/
centerRulerFrame.getComponentViewRect = function(component) {
    return {x: component.scrollLeft, y: component.scrollTop, width: component.offsetWidth, height: component.offsetHeight};
};
//设置component
leftRulerFrame.setComponent(tablePane); 
centerRulerFrame.setComponent(scrollableDiv);</code></pre>    <hr id="contact" style="margin: 20px 0 1px 0">
    <a href="http://www.hightopo.com"><img class="logo"></a>欢迎交流 <a href="mailto:service@hightopo.com">service@hightopo.com</a>
</body>
</html>
